<!--
    Mango - Open Source M2M - http://mango.serotoninsoftware.com
    Copyright (C) 2006-2011 Serotonin Software Technologies Inc.
    @author Matthew Lohbihler
    
    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see http://www.gnu.org/licenses/.
 -->
<h1>Overview</h1>
<p>
  All attributes of a graphical view and its associated points are editable in the graphical view edit page. Views
  contain a collection of <b>view components</b>, which can be static content or dynamic content based upon one or more
  points.
</p>

<h1>Graphical view attributes</h1>
<p>
  All graphical views have a name by which they are referred within lists of graphical views. This name should, but is 
  not required to, be unique. A view may optionally have a <b>Background image</b> upon which its components are 
  superimposed. Users can use any type of image displayable within a browser for the background image, including GIF, 
  JPEG, and PNG. The <b>Anonymous access</b> attribute determines whether users who have not logged in may access the 
  view. <b>Edit</b> means that anonymous users can set the values of settable points in the view. <b>Read</b> means 
  that anonymous users can access the view, but not set point values. <b>None</b> means that anonymous users may not 
  access the view.
</p>

<h1>View components</h1>
<p>
  View components can be added to a view by selecting the type of component from the list, and clicking the 
  <img src="images/plugin_add.png"/> icon. New components default to being displayed in the center of the view, but can
  be repositioned by dragging and dropping them anywhere within the bounds of the background. Note that point views can 
  overlap one another. During view editing, components are written in the order in which they are defined. This may 
  affect how components will overlay each, when overlap occurs.
</p>

<h1>Static content</h1>
<p>
  Select the <b>HTML</b> component type to add static content. By default the <img src="images/html_add.png"/> icon
  represents the content. (This icon will be used whenever no content is defined.) Since these components are 
  independent of the values of points, they are rendered once at the load of the view and remain unchanged from then on.
  Drag the element to the required location. To edit, hover over the content to expose the editing controls. To change 
  the content, click the (<img src="images/pencil.png"/>) icon and enter any valid html. The content will be written 
  verbatim into the view, so any valid HTML (including Javascript content) can be used. Style classes from CSS files 
  can be referenced, or styles can be defined directly. For example, to add a label the following could be used:
</p>
<pre>
  &lt;span style="background-color:yellow;font-size:25px;font-weight:bold;border:2px solid orange;"&gt;My label&lt;/span&gt;
</pre>
<p>
  This would result in the following: <span style="background-color:yellow;font-size:25px;font-weight:bold;border:2px solid orange;">My label</span>
</p>

<p>
  Static content can also reference content on other servers. For example, external images can be placed on your views:
</p>
<pre>
  &lt;img src="http://bluebrain.epfl.ch/webdav/site/bluebrain/shared/21june_06_singleNeuron_200.jpg"/&gt;
</pre>
<p>
  This would display: <img src="http://bluebrain.epfl.ch/webdav/site/bluebrain/shared/21june_06_singleNeuron_200.jpg"/>
</p>

<h1>Point components</h1>
<p>
  All other component types in the component list depend on one or more points for their rendering. Once a component 
  has been added to the view, its default representation is the generic point icon (<img src="images/icon_comp.png"/>).
  This will be the case until the component has enough information to properly render. Required information depends 
  upon the component type. The view editing page behaves similar to the view page in that the current value of the 
  point is displayed and updated so that users can see exactly how the point will appear on the view.
</p>

<h1>Point component rendering</h1>
<p>
  The rendering of a point component can be changed by hovering over the component to display the editing controls. The 
  controls shown in the view editing page differ from those in the view page except for the information control 
  (<img src="images/information.png"/>), which displays the current value and last change time for the point.
</p>

<p>
  Attributes of the point view can be set by clicking on the point view edit icon (<img src="images/plugin_edit.png"/>). 
  When clicked, an editing panel will be displayed that allows attributes of the point to be overridden within the 
  context of the graphical view. For example, if a point is normally settable, it can be altered so that it is not 
  settable within the view (although non-settable points cannot be made settable). This panel is also where the point 
  or points that back the component can be set. Only points with a data type appropriate to the component will be 
  presented in the point list.
</p>

<p>
  The graphical rendering of a component can be changed by clicking on the graphical rendering icon 
  (<img src="images/graphic.png"/>). When clicked, a panel will be displayed allowing the rendering attributes of the 
  component to be edited. For example, the <b>Analog graphic</b> component can be used to visually quantize a numeric 
  point. Using the <b>Min</b> and <b>Max</b> values, the images are uniformly distributed over the numeric range and 
  displayed appropriately. A <b>Binary Image</b> graphical renderer applies only to binary points, and allows the one 
  of two images to be displayed depending upon the current value of the point. Animated images are supported, so 
  animations can be used to visually indicate when a piece of equipment as running vs. when it is not. The textual 
  representation of a point can also be displayed over the images by selecting the <b>Display Text</b> option. A 
  <b>Simple point</b> displays only the textual representation of the point. 
</p>

<p>
  The <b>Dynamic graphic</b> component is similar to the analog image renderer in that it can visualize a numeric 
  point, but instead of choosing one out of a set of images it dynamically draws the indicator of the value. For 
  example, the pointer can be drawn on a single dial image. To add a new dynamic renderer, add a new subdirectory to 
  the graphics directory and put the static image and an appropriate info file there. Then, add a rendering function to 
  the resources/view.js file. The function must be named according to the name given to the subdirectory. See the Dial 
  graphic as an example.
</p>

<p>
  A <b>Server-side script</b> component can be used to define your own rendering logic. The scripting language used 
  here is JavaScript, also known as ECMAScript. (The full specification for ECMAScript is available 
  <a href="http://www.ecma-international.org/publications/standards/Ecma-262.htm" target="_blank">here</a>.) There are,
  however, no "window" or "document" objects available since the script is evaluated on the server rather than the 
  browser. Instead, the current value of the point is available via the <b>value</b> var, and the timestamp of the 
  sample is given in the <b>time</b> var. In addition, <b>pointComponent</b> and <b>point</b> vars are also defined, 
  with analogous values, and "htmlText" and "renderedText" represent rendered versions of the value. Finally, "events" 
  provides a list of active events for the point, and "hasUnacknowledgedEvent" is a boolean value indicating whether at 
  least one of the active events is not acknowledged.
</p>
<p>
  Any value can be returned from the script, but it will be written verbatim to the point view content, so valid HTML 
  is the most useful. Script content (in &lt;script&gt; tags) can also be included, and will be detected and executed
  in the browser. For example, the following will conditionally display a blinking message when the binary point has 
  the value "1" (translated to "true" for the script):
</p>
<pre>
  if (value)
      return '&lt;blink&gt;&lt;span style="background-color:orange;font-size:15px;font-weight:bold;"&gt;Warning: point is ON&lt;/span&gt;&lt;/blink&gt;';
  return "";
</pre>
<p>
  Note that, on the editing page, if a script returns no content the icon <img src='images/logo_icon.gif'/> will be 
  displayed so that the controls can still be exposed upon hover.
</p>

<p>
  The timestamp of the sample is provided in milliseconds since Jan 1, 1970. It can be converted to an ECMA Date object
  with the following code:
</p>
<pre>
  var d = new Date();
  d.setTime(time);
</pre>
<p>
  The Date object "d" can then be used as necessary in remainder of the script.
</p>

<p>
  Point views can be deleted by clicking the delete point view icon (<img src="images/plugin_delete.png"/>), which is
  exposed on hover.
</p>

<h1>Saving graphical views</h1>
<p>
  All changes to graphical views are saved only when the <b>Save</b> button is clicked. If incorrect changes have been 
  made to a view, they may be aborted by clicking the <b>Cancel</b> button. To delete the entire view, click the 
  <b>Delete</b> button.
</p>